/*
 * Copyright (c) 2021-2023 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup OH_NativeXComponent Native XComponent
 * @{
 *
 * @brief Describes the surface and touch event held by the ArkUI XComponent, which can be used for the EGL/OpenGL ES
 * and media data input and displayed on the ArkUI XComponent.
 *
 * @since 8
 * @version 1.0
 */

/**
 * @file native_interface_xcomponent.h
 *
 * @brief Declares the APIs used to access <b>NativeXComponent</b>.
 * @kit ArkUI
 * @include <ace/xcomponent/native_interface_xcomponent.h>
 * @library libace_ndk.z.so
 * @since 8
 * @version 1.0
 */

#ifndef _NATIVE_INTERFACE_XCOMPONENT_H_
#define _NATIVE_INTERFACE_XCOMPONENT_H_

#include <stdbool.h>
#include <stdint.h>
#ifdef __cplusplus
#include <vector>
#endif

#include "arkui/native_interface_accessibility.h"
#include "arkui/native_type.h"
#include "arkui/ui_input_event.h"

#include "native_xcomponent_key_event.h"

#ifdef __cplusplus
extern "C" {
#endif

#define OH_NATIVE_XCOMPONENT_OBJ ("__NATIVE_XCOMPONENT_OBJ__")
#define OH_NATIVE_XCOMPONENT_MAX_TOUCH_POINTS_NUMBER 10

/** Maximum length of the ArkUI XComponent ID. */
const uint32_t OH_XCOMPONENT_ID_LEN_MAX = 128;
/** Maximum number of identifiable touch points in a touch event. */
const uint32_t OH_MAX_TOUCH_POINTS_NUMBER = 10;

/**
 * @brief Enumerates the API access states.
 *
 * @since 8
 * @version 1.0
 */
enum {
    /** Success. */
    OH_NATIVEXCOMPONENT_RESULT_SUCCESS = 0,
    /** Failure. */
    OH_NATIVEXCOMPONENT_RESULT_FAILED = -1,
    /** Invalid parameter. */
    OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER = -2,
};

/**
 * @brief Enumerates the AI image analyzer error codes of the XComponent.
 *
 * @since 18
 */
typedef enum {
    /** AI image analysis is complete. */
    ARKUI_XCOMPONENT_AI_ANALYSIS_FINISHED = 0,
    /** AI image analysis is disabled. */
    ARKUI_XCOMPONENT_AI_ANALYSIS_DISABLED = 110000,
    /** The device does not support AI image analysis. */
    ARKUI_XCOMPONENT_AI_ANALYSIS_UNSUPPORTED = 110001,
    /** AI image analysis is in progress. */
    ARKUI_XCOMPONENT_AI_ANALYSIS_ONGOING = 110002,
    /** AI image analysis has been stopped. */
    ARKUI_XCOMPONENT_AI_ANALYSIS_STOPPED = 110003,
} ArkUI_XComponent_ImageAnalyzerState;

/**
 * @brief Enumerates touch event types.
 * @since 8
 */
typedef enum {
    /** The touch event is triggered when a finger is pressed. */
    OH_NATIVEXCOMPONENT_DOWN = 0,
    /** The touch event is triggered when a finger is lifted. */
    OH_NATIVEXCOMPONENT_UP,
    /** The touch event is triggered when a finger is moved on the screen. */
    OH_NATIVEXCOMPONENT_MOVE,
    /** The touch event is triggered when a touch is canceled. */
    OH_NATIVEXCOMPONENT_CANCEL,
    /** Invalid touch type. */
    OH_NATIVEXCOMPONENT_UNKNOWN,
} OH_NativeXComponent_TouchEventType;

/**
 * @brief Enumerates touch point tool types.
 *
 * @since 9
 * @version 1.0
 */
typedef enum {
    /** Unknown tool type. */
    OH_NATIVEXCOMPONENT_TOOL_TYPE_UNKNOWN = 0,
    /** Finger. */
    OH_NATIVEXCOMPONENT_TOOL_TYPE_FINGER,
    /** Stylus. */
    OH_NATIVEXCOMPONENT_TOOL_TYPE_PEN,
    /** Rubber. */
    OH_NATIVEXCOMPONENT_TOOL_TYPE_RUBBER,
    /** Brush. */
    OH_NATIVEXCOMPONENT_TOOL_TYPE_BRUSH,
    /** Pencil. */
    OH_NATIVEXCOMPONENT_TOOL_TYPE_PENCIL,
    /** Air brush. */
    OH_NATIVEXCOMPONENT_TOOL_TYPE_AIRBRUSH,
    /** Mouse. */
    OH_NATIVEXCOMPONENT_TOOL_TYPE_MOUSE,
    /** Lens. */
    OH_NATIVEXCOMPONENT_TOOL_TYPE_LENS,
} OH_NativeXComponent_TouchPointToolType;

/**
 * @brief Enumerates touch event source types.
 *
 * @since 9
 * @version 1.0
 */
typedef enum {
    /** Unknown source type. */
    OH_NATIVEXCOMPONENT_SOURCE_TYPE_UNKNOWN = 0,
    /** Source that generates a mouse multi-click event. */
    OH_NATIVEXCOMPONENT_SOURCE_TYPE_MOUSE,
    /** Source that generates a touchscreen multi-touch event. */
    OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHSCREEN,
    /** Source that generates a touchpad multi-touch event. */
    OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHPAD,
    /** Source that generates a joystick multi-touch event. */
    OH_NATIVEXCOMPONENT_SOURCE_TYPE_JOYSTICK,
    /**
     * @brief Describes the source that generates a key event.
     *
     * @since 10
     * @version 1.0
     */
    OH_NATIVEXCOMPONENT_SOURCE_TYPE_KEYBOARD,
} OH_NativeXComponent_EventSourceType;

/**
 * @brief Enumerates the mouse event actions.
 *
 * @since 9
 * @version 1.0
 */
typedef enum {
    /** Invalid mouse event. */
    OH_NATIVEXCOMPONENT_MOUSE_NONE = 0,
    /** Mouse button press. */
    OH_NATIVEXCOMPONENT_MOUSE_PRESS,
    /** Mouse button release. */
    OH_NATIVEXCOMPONENT_MOUSE_RELEASE,
    /** Mouse movement. */
    OH_NATIVEXCOMPONENT_MOUSE_MOVE,
    /** Mouse button release.
     * @since 18
    */
    OH_NATIVEXCOMPONENT_MOUSE_CANCEL,
} OH_NativeXComponent_MouseEventAction;

/**
 * @brief Enumerates the mouse event buttons.
 *
 * @since 9
 * @version 1.0
 */
typedef enum {
    /** No button. */
    OH_NATIVEXCOMPONENT_NONE_BUTTON = 0,
    /** Left mouse button. */
    OH_NATIVEXCOMPONENT_LEFT_BUTTON = 0x01,
    /** Right mouse button. */
    OH_NATIVEXCOMPONENT_RIGHT_BUTTON = 0x02,
    /** Middle mouse button. */
    OH_NATIVEXCOMPONENT_MIDDLE_BUTTON = 0x04,
    /** Back button on the left of the mouse. */
    OH_NATIVEXCOMPONENT_BACK_BUTTON = 0x08,
    /** Forward key on the left of the mouse. */
    OH_NATIVEXCOMPONENT_FORWARD_BUTTON = 0x10,
} OH_NativeXComponent_MouseEventButton;

/**
 * @brief Enumerates the source tool types of touch events.
 *
 * @since 10
 * @version 1.0
 */
typedef enum {
    /** Unknown source tool. */
    OH_NATIVEXCOMPONENT_SOURCETOOL_UNKNOWN = 0,
    /** Finger. */
    OH_NATIVEXCOMPONENT_SOURCETOOL_FINGER = 1,
    /** Pen. */
    OH_NATIVEXCOMPONENT_SOURCETOOL_PEN = 2,
    /** Eraser. */
    OH_NATIVEXCOMPONENT_SOURCETOOL_RUBBER = 3,
    /** Brush. */
    OH_NATIVEXCOMPONENT_SOURCETOOL_BRUSH = 4,
    /** Pencil. */
    OH_NATIVEXCOMPONENT_SOURCETOOL_PENCIL = 5,
    /** Airbrush. */
    OH_NATIVEXCOMPONENT_SOURCETOOL_AIRBRUSH = 6,
    /** Mouse pointer. */
    OH_NATIVEXCOMPONENT_SOURCETOOL_MOUSE = 7,
    /** Lens. */
    OH_NATIVEXCOMPONENT_SOURCETOOL_LENS = 8,
    /** Touchpad. */
    OH_NATIVEXCOMPONENT_SOURCETOOL_TOUCHPAD = 9,
} OH_NativeXComponent_TouchEvent_SourceTool;

/**
 * @brief Represents a historical touch point.
 *
 * @since 10
 * @version 1.0
 */
typedef struct {
    /** Unique identifier of the finger. */
    int32_t id;
    /** X coordinate of the touch point relative to the left edge of the application window where the XComponent is
      * located.
      */
    float screenX;
    /** Y coordinate of the touch point relative to the left edge of the application window where the XComponent is
      * located.
      */
    float screenY;
    /** X coordinate of the touch point relative to the left edge of the XComponent. */
    float x;
    /** Y coordinate of the touch point relative to the upper edge of the XComponent. */
    float y;
    /** Touch type of the touch point. */
    OH_NativeXComponent_TouchEventType type;
    /** Contact area between the finger pad and the screen. */
    double size;
    /** Pressure of the touch event. */
    float force;
    /** Timestamp of the touch point. It is interval between the time when the event is triggered and the time
     *  when the system starts, in nanoseconds. */
    int64_t timeStamp;
    /** Angle between the projection on the x-y plane and the z-axis of the touch event. */
    float titlX;
    /** Angle between the projection on the y-z plane and the z-axis of the current touch event. */
    float titlY;
    /** Source tool of the touch event. */
    OH_NativeXComponent_TouchEvent_SourceTool sourceTool;
} OH_NativeXComponent_HistoricalPoint;

/**
 * @brief Describes the touch point of the touch event.
 *
 * @since 8
 * @version 1.0
 */
typedef struct {
    /** Unique identifier of the finger. */
    int32_t id;
    /** X coordinate of the touch point relative to the left edge of the application window where the XComponent is
     *  located. */
    float screenX;
    /** Y coordinate of the touch point relative to the left edge of the application window where the XComponent is
     *  located. */
    float screenY;
    /** X coordinate of the touch point relative to the left edge of the XComponent. */
    float x;
    /** Y coordinate of the touch point relative to the upper edge of the XComponent. */
    float y;
    /** Touch type of the touch point. */
    OH_NativeXComponent_TouchEventType type;
    /** Contact area between the finger pad and the screen. */
    double size;
    /** Pressure of the touch event. */
    float force;
    /** Timestamp of the touch point. It is interval between the time when the event is triggered and the time when the
     *  system starts, in nanoseconds. */
    long long timeStamp;
    /** Whether the current point is pressed. */
    bool isPressed;
} OH_NativeXComponent_TouchPoint;

/**
 * @brief Describes the touch event.
 *
 * @since 8
 * @version 1.0
 */
typedef struct {
    /** Unique identifier of the finger. */
    int32_t id;
    /** X coordinate of the touch point relative to the upper left corner of the application window where the XComponent
     *  is located. */
    float screenX;
    /** Y coordinate of the touch point relative to the upper left corner of the application window where the XComponent
     *  is located. */
    float screenY;
    /** X coordinate of the touch point relative to the left edge of the XComponent. */
    float x;
    /** Y coordinate of the touch point relative to the upper edge of the XComponent. */
    float y;
    /** Touch type of the touch point. */
    OH_NativeXComponent_TouchEventType type;
    /** Contact area between the finger pad and the screen. */
    double size;
    /** Pressure of the touch event. */
    float force;
    /** ID of the device where the current touch event is triggered. */
    int64_t deviceId;
    /** Timestamp of the touch point. It is interval between the time when the event is triggered and the time when
     *  the system starts, in nanoseconds. */
    long long timeStamp;
    /** Array of the touch points. */
    OH_NativeXComponent_TouchPoint touchPoints[OH_MAX_TOUCH_POINTS_NUMBER];
    /** Number of current touch points. */
    uint32_t numPoints;
} OH_NativeXComponent_TouchEvent;

/**
 * @brief Describes the mouse event.
 *
 * @since 9
 * @version 1.0
 */
typedef struct {
    /** X coordinate of the clicked point relative to the upper left corner of the component. */
    float x;
    /** Y coordinate of the clicked point relative to the upper left corner of the component. */
    float y;
    /** X coordinate of the clicked point relative to the upper left corner of the application screen where the
     *  XComponent is located. */
    float screenX;
    /** Y coordinate of the clicked point relative to the upper left corner of the application window where the
     *  XComponent is located. */
    float screenY;
    /** Timestamp of the mouse event. It is interval between the time when the event is triggered and the time when
     *  the system starts, in nanoseconds. */
    int64_t timestamp;
    /** Action of the mouse event. */
    OH_NativeXComponent_MouseEventAction action;
    /** Mouse event button. */
    OH_NativeXComponent_MouseEventButton button;
} OH_NativeXComponent_MouseEvent;

/**
 * @brief Provides an encapsulated <b>OH_NativeXComponent</b> instance.
 *
 * @since 8
 * @version 1.0
 */
typedef struct OH_NativeXComponent OH_NativeXComponent;

/**
 * @brief Registers callbacks for the surface lifecycle and touch event.
 *
 * @since 8
 * @version 1.0
 */
typedef struct OH_NativeXComponent_Callback {
    /**
     * @brief Invoked when a surface is created.
     *
     * @param component Pointer to the {@link OH_NativeXComponent} instance.
     * @param window Indicates the handle to the <b>NativeWindow</b> instance.
     * @since 8
     * @version 1.0
     */
    void (*OnSurfaceCreated)(OH_NativeXComponent* component, void* window);

    /**
     * @brief Invoked when the surface changes.
     *
     * @param component Pointer to the {@link OH_NativeXComponent} instance.
     * @param window Indicates the handle to the <b>NativeWindow</b> instance.
     * @since 8
     * @version 1.0
     */
    void (*OnSurfaceChanged)(OH_NativeXComponent* component, void* window);

    /**
     * @brief Invoked when the surface is destroyed.
     *
     * @param component Pointer to the {@link OH_NativeXComponent} instance.
     * @param window Indicates the handle to the <b>NativeWindow</b> instance.
     * @since 8
     * @version 1.0
     */
    void (*OnSurfaceDestroyed)(OH_NativeXComponent* component, void* window);

    /**
     * @brief Invoked when a touch event is triggered.
     *
     * @param component Pointer to the {@link OH_NativeXComponent} instance.
     * @param window Indicates the handle to the <b>NativeWindow</b> instance.
     * @since 8
     * @version 1.0
     */
    void (*DispatchTouchEvent)(OH_NativeXComponent* component, void* window);
} OH_NativeXComponent_Callback;

/**
 * @brief Registers callbacks for the mouse event.
 *
 * @since 9
 * @version 1.0
 */
typedef struct OH_NativeXComponent_MouseEvent_Callback {
    /**
     * @brief Invoked when a mouse event is triggered.
     *
     * @param component Pointer to the {@link OH_NativeXComponent} instance.
     * @param window Indicates the handle to the <b>NativeWindow</b> instance.
     * @since 8
     * @version 1.0
     */
    void (*DispatchMouseEvent)(OH_NativeXComponent* component, void* window);

    /**
     * @brief Invoked when a hover event is triggered.
     *
     * @param component Pointer to the {@link OH_NativeXComponent} instance.
     * @param isHover Whether the mouse pointer or stylus is hovering over the component.
     *                <b>true</b>: The mouse pointer or stylus has entered the component.
     *                <b>false</b>: The mouse pointer or stylus has left the component.
     * @since 8
     * @version 1.0
     */
    void (*DispatchHoverEvent)(OH_NativeXComponent* component, bool isHover);
} OH_NativeXComponent_MouseEvent_Callback;

/**
 * @brief Defines a struct for the XComponent key event.
 *
 * @since 10
 * @version 1.0
 */
typedef struct OH_NativeXComponent_KeyEvent OH_NativeXComponent_KeyEvent;

/**
 * @brief Defines the expected frame rate range.
 *
 * @since 11
 * @version 1.0
 */
typedef struct {
    /** Minimum value of the expected frame rate range. */
    int32_t min;
    /** Maximum value of the expected frame rate range. */
    int32_t max;
    /** Expected frame rate range. */
    int32_t expected;
} OH_NativeXComponent_ExpectedRateRange;

/**
 * @brief Obtains the ID of the ArkUI XComponent.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param id Pointer to the character buffer for storing the ID of the {@link OH_NativeXComponent} instance.
 * Note that null terminators will be attached to the character buffer, so the size of the character buffer
 * should be at least one unit greater than the length of the real ID.
 * The recommended size is [OH_XCOMPONENT_ID_LEN_MAX + 1].
 * @param size Pointer to the length of the ID, used to receive the length information of the ID.
 * @return Returns the status code of the execution.
 * @since 8
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetXComponentId(OH_NativeXComponent* component, char* id, uint64_t* size);

/**
 * @brief Obtains the size of the surface held by the ArkUI XComponent.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param window Indicates the handle to the <b>NativeWindow</b> instance.
 * @param width Pointer to the width of the current surface.
 * @param height Pointer to the height of the current surface.
 * @return Returns the status code of the execution.
 * @since 8
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetXComponentSize(
    OH_NativeXComponent* component, const void* window, uint64_t* width, uint64_t* height);

/**
 * @brief Obtains the offset of the surface held by the XComponent relative to the upper left corner of its parent
 *        component.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param window Indicates the handle to the <b>NativeWindow</b> instance.
 * @param x Pointer to the X coordinate of the current surface relative to the upper left corner of the XComponent's
 *          parent component.
 * @param y Pointer to the Y coordinate of the current surface relative to the upper left corner of the XComponent's
 *          parent component.
 * @return Returns the status code of the execution.
 * @since 8
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetXComponentOffset(
    OH_NativeXComponent* component, const void* window, double* x, double* y);

/**
 * @brief Obtains the touch event scheduled by the ArkUI XComponent.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param window Indicates the handle to the <b>NativeWindow</b> instance.
 * @param touchEvent Pointer to the current touch event.
 * @return Returns the status code of the execution.
 * @since 8
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetTouchEvent(
    OH_NativeXComponent* component, const void* window, OH_NativeXComponent_TouchEvent* touchEvent);

/**
 * @brief Obtains the ArkUI XComponent touch point tool type.
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param pointIndex Pointer to the index of the touch point.
 * @param toolType Pointer to the tool type.
 * @return Result code.
 * @since 9
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetTouchPointToolType(OH_NativeXComponent* component, uint32_t pointIndex,
    OH_NativeXComponent_TouchPointToolType* toolType);

/**
 * @brief Obtains the angle between the ArkUI XComponent touch point and the x-axis.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param pointIndex Pointer to the index of the touch point.
 * @param tiltX Pointer to the angle between the touch point and the x-axis.
 * @return Result code.
 * @since 9
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetTouchPointTiltX(OH_NativeXComponent* component, uint32_t pointIndex, float* tiltX);

/**
 * @brief Obtains the angle between the ArkUI XComponent touch point and the y-axis.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param pointIndex Pointer to the index of the touch point.
 * @param tiltY Pointer to the angle between the touch point and the y-axis.
 * @return Result code.
 * @since 9
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetTouchPointTiltY(OH_NativeXComponent* component, uint32_t pointIndex, float* tiltY);

/**
 * @brief Obtains the X coordinate of the touch point relative to the upper left corner of the application window where
 *        the ArkUI XComponent is located.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param pointIndex Pointer to the index of the touch point.
 * @param windowX Pointer to the X coordinate of the touch point relative to the upper left corner of
 *                the application window.
 * @return Result code.
 *         {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS}: The operation is successful.
 *         {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER}: The component, windowX, or native XComponent is
 *         a null pointer.
 * @since 12
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetTouchPointWindowX(OH_NativeXComponent* component, uint32_t pointIndex, float* windowX);

/**
 * @brief Obtains the Y coordinate of the touch point relative to the upper left corner of the application window where
 *        the ArkUI XComponent is located.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param pointIndex Pointer to the index of the touch point.
 * @param windowY Pointer to the Y coordinate of the touch point relative to the upper left corner of the
 *                application window.
 * @return Result code.
 *         {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS}: The operation is successful.
 *         {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER}: The component, windowY, or native XComponent is
 *         a null pointer.
 * @since 12
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetTouchPointWindowY(OH_NativeXComponent* component, uint32_t pointIndex, float* windowY);

/**
 * @brief Obtains the X coordinate of the touch point relative to the upper left corner of the screen where the
 *        ArkUI XComponent is located.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param pointIndex Pointer to the index of the touch point.
 * @param displayX Pointer to the X coordinate of the touch point relative to the upper left corner of the screen.
 * @return Result code.
 *         {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS}: The operation is successful.
 *         {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER}: The component, displayX, or native XComponent is
 *         a null pointer.
 * @since 12
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetTouchPointDisplayX(OH_NativeXComponent* component, uint32_t pointIndex, float* displayX);

/**
 * @brief Obtains the Y coordinate of the touch point relative to the upper left corner of the screen where the ArkUI
 *        XComponent is located.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param pointIndex Pointer to the index of the touch point.
 * @param displayY Pointer to the Y coordinate of the touch point relative to the upper left corner of the screen.
 * @return Result code.
 *         {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS}: The operation is successful.
 *         {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER}: The component, displayY, or native XComponent is
 *         a null pointer.
 * @since 12
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetTouchPointDisplayY(OH_NativeXComponent* component, uint32_t pointIndex, float* displayY);

/**
 * @brief Obtains the historical touch point data for the touch event of an <b>OH_NativeXComponent</b> instance.
 * Some input devices report touch points at very high frequencies (up to 1 ms intervals). However, since UI updates
 * typically do not require such high-frequency updates,
 * the system consolidates touch events and reports them once per frame.
 * All touch points collected during the current frame are preserved as historical touch points for applications that
 * need direct access to this raw data.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param window Indicates the handle to the <b>NativeWindow</b> instance.
 * @param size Length of the historical touch point array.
 * @param size Pointer to the historical touch point array.
 * @return Result code.
 * @since 10
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetHistoricalPoints(OH_NativeXComponent* component, const void* window,
    int32_t* size, OH_NativeXComponent_HistoricalPoint** historicalPoints);

/**
 * @brief Obtains the mouse event scheduled by ArkUI XComponent.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param window Indicates the handle to the <b>NativeWindow</b> instance.
 * @param mouseEvent Pointer to the current mouse event.
 * @return Result code.
 * @since 9
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetMouseEvent(
    OH_NativeXComponent* component, const void* window, OH_NativeXComponent_MouseEvent* mouseEvent);

/**
 * @brief Registers a callback for this {@link OH_NativeXComponent} instance.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the surface lifecycle and touch event callback.
 * @return Result code.
 * @since 8
 * @version 1.0
 */
int32_t OH_NativeXComponent_RegisterCallback(OH_NativeXComponent* component, OH_NativeXComponent_Callback* callback);

/**
 * @brief Registers a mouse event callback for this {@link OH_NativeXComponent} instance.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the mouse event callback.
 * @return Result code.
 * @since 9
 * @version 1.0
 */
int32_t OH_NativeXComponent_RegisterMouseEventCallback(
    OH_NativeXComponent* component, OH_NativeXComponent_MouseEvent_Callback* callback);

/**
 * @brief Provides an encapsulated instance of extended mouse event information.
 *
 * @since 20
 * @version 1.0
 */
typedef struct OH_NativeXComponent_ExtraMouseEventInfo OH_NativeXComponent_ExtraMouseEventInfo;

/**
 * @brief Obtains extended mouse event information from an {@link OH_NativeXComponent} instance.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param extraMouseEventInfo Address of a pointer to the {@link OH_NativeXComponent_ExtraMouseEventInfo} type.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 20
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetExtraMouseEventInfo(
    OH_NativeXComponent* component, OH_NativeXComponent_ExtraMouseEventInfo** extraMouseEventInfo);

/**
 * @brief Obtains the state of modifier keys from an {@link OH_NativeXComponent_ExtraMouseEventInfo} instance.
 *
 * @param extraMouseEventInfo Pointer to the extended mouse event information instance.
 * @param keys Address of a 64-bit unsigned integer to receive the modifier key press state information.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 20
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetMouseEventModifierKeyStates(
    OH_NativeXComponent_ExtraMouseEventInfo* extraMouseEventInfo, uint64_t* keys);

/**
 * @brief Registers a focus event callback for this {@link OH_NativeXComponent} instance.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the focus event callback.
 *                 - <b>window</b>: handle to the <b>NativeWindow</b> instance.
 * @return Result code.
 * @since 10
 * @version 1.0
 */
int32_t OH_NativeXComponent_RegisterFocusEventCallback(
    OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window));

/**
 * @brief Registers a key event callback for this {@link OH_NativeXComponent} instance.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the key event callback.
 *                 - <b>window</b>: handle to the <b>NativeWindow</b> instance.
 * @return Result code.
 * @since 10
 * @version 1.0
 */
int32_t OH_NativeXComponent_RegisterKeyEventCallback(
    OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window));

/**
 * @brief Registers a focus event callback for this {@link OH_NativeXComponent} instance.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the blur event callback.
 *                 - <b>window</b>: handle to the <b>NativeWindow</b> instance.
 * @return Result code.
 * @since 10
 * @version 1.0
 */
int32_t OH_NativeXComponent_RegisterBlurEventCallback(
    OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window));

/**
 * @brief Obtains the key event scheduled by the ArkUI XComponent.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param keyEvent Pointer to the current key event.
 * @return Result code.
 * @since 10
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetKeyEvent(OH_NativeXComponent* component, OH_NativeXComponent_KeyEvent** keyEvent);

/**
 * @brief Obtains the action of a key event.
 *
 * @param keyEvent Pointer to the {@link OH_NativeXComponent_KeyEvent} instance.
 * @param action Pointer to the key event action.
 * @return Result code.
 * @since 10
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetKeyEventAction(
    OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_KeyAction* action);

/**
 * @brief Obtains the key code of a key event.
 *
 * @param keyEvent Pointer to the {@link OH_NativeXComponent_KeyEvent} instance.
 * @param code Pointer to the key code of the key event.
 * @return Result code.
 * @since 10
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetKeyEventCode(OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_KeyCode* code);

/**
 * @brief Obtains the source type of a key event.
 *
 * @param keyEvent Pointer to the {@link OH_NativeXComponent_KeyEvent} instance.
 * @param sourceType Pointer to the key event source type.
 * @return Result code.
 * @since 10
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetKeyEventSourceType(
    OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_EventSourceType* sourceType);

/**
 * @brief Obtains the device ID of a key event.
 *
 * @param keyEvent Pointer to the {@link OH_NativeXComponent_KeyEvent} instance.
 * @param deviceId Pointer to the key event device ID.
 * @return Result code.
 * @since 10
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetKeyEventDeviceId(OH_NativeXComponent_KeyEvent* keyEvent, int64_t* deviceId);

/**
 * @brief Obtains the timestamp of a key event.
 *
 * @param keyEvent Pointer to the {@link OH_NativeXComponent_KeyEvent} instance.
 * @param timestamp Pointer to the timestamp of the key event.
 * @return Result code.
 * @since 10
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetKeyEventTimestamp(OH_NativeXComponent_KeyEvent* keyEvent, int64_t* timestamp);

/**
 * @brief Obtains the state of modifier keys from a key event.
 *
 * @param keyEvent Pointer to the key event.
 * @param keys Address of a 64-bit unsigned integer to receive the modifier key press state information.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 20
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetKeyEventModifierKeyStates(OH_NativeXComponent_KeyEvent* keyEvent, uint64_t* keys);

/**
 * @brief Obtains the state of the NumLock key from a key event.
 *
 * @param keyEvent Pointer to the key event.
 * @param isNumLockOn Address of a boolean variable to receive the state of the NumLock key.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 20
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetKeyEventNumLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isNumLockOn);

/**
 * @brief Obtains the state of the CapsLock key from a key event.
 *
 * @param keyEvent Pointer to the key event.
 * @param isCapsLockOn Address of a boolean variable to receive the state of the CapsLock key.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 20
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetKeyEventCapsLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isCapsLockOn);

/**
 * @brief Obtains the state of the ScrollLock key from a key event.
 *
 * @param keyEvent Pointer to the key event.
 * @param isScrollLockOn Address of a boolean variable to receive the state of the ScrollLock key.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 20
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetKeyEventScrollLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isScrollLockOn);

/**
 * @brief Sets the expected frame rate range.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param range Expected frame rate information object of the {@link OH_NativeXComponent_ExpectedRateRange} type.
 * @return Result code.
 * @since 11
 * @version 1.0
 */
int32_t OH_NativeXComponent_SetExpectedFrameRateRange(
    OH_NativeXComponent* component, OH_NativeXComponent_ExpectedRateRange* range);

/**
 * @brief Registers a display update callback for this {@link OH_NativeXComponent} instance and
 *        enables the callback for each frame.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the display update callback.
 *                 - <b>timestamp</b>: time when the current frame arrives, in nanoseconds.
 *                 - <b>targetTimestamp</b>: expected arrival time of the next frame, in nanoseconds.
 * @return Result code.
 * @since 11
 * @version 1.0
 */
int32_t OH_NativeXComponent_RegisterOnFrameCallback(OH_NativeXComponent* component,
    void (*callback)(OH_NativeXComponent* component, uint64_t timestamp, uint64_t targetTimestamp));

/**
 * @brief Deregisters the display update callback for an {@link OH_NativeXComponent} instance and disables the callback
 *        for each frame.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @return Result code.
 * @since 11
 * @version 1.0
 */
int32_t OH_NativeXComponent_UnregisterOnFrameCallback(OH_NativeXComponent* component);

/**
 * @brief Attaches the UI component created through the native API of ArkUI to this <b>OH_NativeXComponent</b> instance.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param root Pointer to the component instance created through the native API.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 *
 * @since 12
 * @deprecated since 20
 * @useinstead {@link OH_ArkUI_NodeContent_AddNode}
 */
int32_t OH_NativeXComponent_AttachNativeRootNode(OH_NativeXComponent* component, ArkUI_NodeHandle root);

/**
 * @brief Detaches the native component of ArkUI from this <b>OH_NativeXComponent</b> instance.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param root Pointer to the component instance created through the native API.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 *
 * @since 12
 * @deprecated since 20
 * @useinstead {@link OH_ArkUI_NodeContent_RemoveNode}
 */
int32_t OH_NativeXComponent_DetachNativeRootNode(OH_NativeXComponent* component, ArkUI_NodeHandle root);

/**
 * @brief Registers a UI input event callback for an {@link OH_NativeXComponent} instance and enables the callback to
 *        be invoked when a UI input event is received. Currently, only axis events are supported.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the UI input event callback.
 *                 - <b>event</b>: pointer to the UI input event.
 * @param type Type of the current UI input event.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 *
 * @since 12
 */
int32_t OH_NativeXComponent_RegisterUIInputEventCallback(
    OH_NativeXComponent *component,
    void (*callback)(OH_NativeXComponent *component, ArkUI_UIInputEvent *event,
                     ArkUI_UIInputEvent_Type type),
    ArkUI_UIInputEvent_Type type);

/**
 * @brief Registers a custom event intercept callback for an {@link OH_NativeXComponent} instance.
 *        This enables the specified during hit testing.
 *        UI input-rrelated operations are not supported on event objects received through this callback.
 *        For full functionality, use the <b>NODE_ON_TOUCH_INTERCEPT</b> event on native nodes instead.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the custom event intercept callback.
 *                 - <b>event</b>: pointer to the UI input event.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 12
 */
int32_t OH_NativeXComponent_RegisterOnTouchInterceptCallback(
    OH_NativeXComponent* component, HitTestMode (*callback)(OH_NativeXComponent* component, ArkUI_UIInputEvent* event));

/**
 * @brief Specifies whether a soft keyboard is required for an {@link OH_NativeXComponent} instance.
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param needSoftKeyboard Whether a soft keyboard is required.
 * @return Result code.
 * @since 12
 * @version 1.0
 */
int32_t OH_NativeXComponent_SetNeedSoftKeyboard(OH_NativeXComponent* component, bool needSoftKeyboard);

/**
 * @brief Registers a surface display callback for an {@link OH_NativeXComponent} instance.
 *        The callback is invoked when the application window has returned to the foreground from the background.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the surface display callback.
 *                 - <b>window</b>: handle to the <b>NativeWindow</b> instance.
 * @return Result code.
 * @since 12
 * @version 1.0
 */
int32_t OH_NativeXComponent_RegisterSurfaceShowCallback(
    OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window));

/**
 * @brief Registers a surface hiding callback for an {@link OH_NativeXComponent} instance.
 *        The callback is invoked when the application window has entered the background from the foreground.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the surface hiding callback.
 *                 - <b>window</b>: handle to the <b>NativeWindow</b> instance.
 * @return Result code.
 * @since 12
 * @version 1.0
 */
int32_t OH_NativeXComponent_RegisterSurfaceHideCallback(
    OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window));

/**
 * @brief Obtains the touch event source type of an <b>OH_NativeXComponent</b> instance.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param pointId ID of a touch point. The touch event source type can be correctly returned only when the ID passed
 *                in is the ID of the touch point that triggers the touch event. Otherwise,
 *                <b>OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER</b> is returned.
 * @param sourceType Pointer to the touch event source type.
 * @return <b>OH_NATIVEXCOMPONENT_RESULT_SUCCESS</b>: The operation is successful.
 *         <b>OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER</b>: A parameter error occurs.
 *         <b>OH_NATIVEXCOMPONENT_RESULT_FAILED</b>: Any other error occurs.
 * @since 12
 * @version 1.0
 */
int32_t OH_NativeXComponent_GetTouchEventSourceType(
    OH_NativeXComponent* component, int32_t pointId, OH_NativeXComponent_EventSourceType* sourceType);

/**
 * @brief Obtains the pointer to an {@link OH_NativeXComponent} instance based on the specified component instance
 *        created by the native API.
 *
 * @param node Pointer to the component instance created by the native API.
 * @return Pointer to the {@link OH_NativeXComponent} instance.
 * @since 12
 * @version 1.0
 */
OH_NativeXComponent* OH_NativeXComponent_GetNativeXComponent(ArkUI_NodeHandle node);

/**
 * @brief Obtains the accessibility provider handle for an ArkUI XComponent.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param handle Pointer to the {@link ArkUI_AccessibilityProvider} instance.
 * @return Returns <b>OH_NATIVEXCOMPONENT_RESULT_SUCCESS</b> if the operation is successful.
 *         Returns <b>OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER</b> if a parameter error occurs.
 *         Returns <b>OH_NATIVEXCOMPONENT_RESULT_FAILED</b> if any other error occurs.
 * @since 13
 */
int32_t OH_NativeXComponent_GetNativeAccessibilityProvider(
    OH_NativeXComponent* component, ArkUI_AccessibilityProvider** handle);

/**
 * @brief Registers a key event callback with a return value for this {@link OH_NativeXComponent} instance.
 * The callback must return a result (<b>true</b> or <b>false</b>).
 * If the callback returns <b>true</b>, the event will not be further propagated. If it returns <b>false</b>,
 * the event will continue to be processed according to the normal event handling flow.
 *
 * @param component Pointer to the {@link OH_NativeXComponent} instance.
 * @param callback Pointer to the key event callback.
 *                 - <b>window</b>: handle to the <b>NativeWindow</b> instance.
 * @return Result code.
 *         <b>OH_NATIVEXCOMPONENT_RESULT_SUCCESS</b>: The operation is successful.
 *         <b>OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER</b>: A parameter error occurs.
 * @since 14
 * @version 1.0
 */
int32_t OH_NativeXComponent_RegisterKeyEventCallbackWithResult(
    OH_NativeXComponent* component, bool (*callback)(OH_NativeXComponent* component, void* window));

/**
 * @brief Starts AI image analysis for this XComponent instance.
 *        Before calling this API, make sure the AI image analyzer is enabled.
 *
 * @param node XComponent instance.
 * @param userData Pointer to the data that you need to obtain when the callback function is executed.
 * @param callback Callback function triggered when the AI image analysis status is updated.
 *                 - <b>statusCode</b>: one of the input parameters of the callback function,
 *                                      indicating the current image analysis status.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 18
 */
int32_t OH_ArkUI_XComponent_StartImageAnalyzer(ArkUI_NodeHandle node, void* userData,
    void (*callback)(ArkUI_NodeHandle node, ArkUI_XComponent_ImageAnalyzerState statusCode, void* userData));

/**
 * @brief Stops AI image analysis for this XComponent instance.
 *
 * @param node XComponent instance.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 18
 */
int32_t OH_ArkUI_XComponent_StopImageAnalyzer(ArkUI_NodeHandle node);

/**
 * @brief Defines a struct for the <b>OH_ArkUI_SurfaceHolder</b> instance.
 *
 * @since 19
 */
typedef struct OH_ArkUI_SurfaceHolder OH_ArkUI_SurfaceHolder;

/**
 * @brief Creates an {@link OH_ArkUI_SurfaceHolder} object for an <b>XComponent</b> component.
 *
 * @param node Pointer to the XComponent instance created through the native API.
 * @return Pointer to the created {@link OH_ArkUI_SurfaceHolder} object.
 * @since 19
 */
OH_ArkUI_SurfaceHolder* OH_ArkUI_SurfaceHolder_Create(ArkUI_NodeHandle node);

/**
 * @brief Disposes of an {@link OH_ArkUI_SurfaceHolder} object.
 *
 * @param node Pointer to the {@link OH_ArkUI_SurfaceHolder} object to be disposed of.
 * @since 19
 */
void OH_ArkUI_SurfaceHolder_Dispose(OH_ArkUI_SurfaceHolder* surfaceHolder);

/**
 * @brief Stores custom data in an {@link OH_ArkUI_SurfaceHolder} instance.
 *
 * @param surfaceHolder Pointer to the {@link OH_ArkUI_SurfaceHolder} instance where the custom data will be stored.
 * @param userData Pointer to the custom data to be stored.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 19
 */
int32_t OH_ArkUI_SurfaceHolder_SetUserData(OH_ArkUI_SurfaceHolder* surfaceHolder, void* userData);

/**
 * @brief Obtains the custom data stored in an {@link OH_ArkUI_SurfaceHolder} instance.
 *
 * @param surfaceHolder Pointer to the {@link OH_ArkUI_SurfaceHolder} instance where the custom data is stored.
 * @return Custom data.
 * @since 19
 */
void* OH_ArkUI_SurfaceHolder_GetUserData(OH_ArkUI_SurfaceHolder* surfaceHolder);

/**
 * @brief Defines surface lifecycle callback functions.
 *
 * @since 19
 */
typedef struct OH_ArkUI_SurfaceCallback OH_ArkUI_SurfaceCallback;

/**
 * @brief Creates an {@link OH_ArkUI_SurfaceCallback} object.
 *
 * @return Pointer to the created {@link OH_ArkUI_SurfaceCallback} object.
 * @since 19
 */
OH_ArkUI_SurfaceCallback* OH_ArkUI_SurfaceCallback_Create();

/**
 * @brief Disposes of an {@link OH_ArkUI_SurfaceCallback} object.
 *
 * @param callback Pointer to the {@link OH_ArkUI_SurfaceCallback} object to be disposed of.
 * @since 19
 */
void OH_ArkUI_SurfaceCallback_Dispose(OH_ArkUI_SurfaceCallback* callback);

/**
 * @brief Sets the creation callback event in the surface lifecycle callbacks.
 *
 * @param callback Pointer to the surface lifecycle callback.
 * @param onSurfaceCreated Callback event triggered when the surface is created.
 *                         - <b>surfaceHolder</b>: pointer to the {@link OH_ArkUI_SurfaceHolder} instance.
 * @since 19
 */
void OH_ArkUI_SurfaceCallback_SetSurfaceCreatedEvent(
    OH_ArkUI_SurfaceCallback* callback,
    void (*onSurfaceCreated)(OH_ArkUI_SurfaceHolder* surfaceHolder));

/**
 * @brief Sets the size change callback event in the surface lifecycle callback.
 *
 * @param callback Pointer to the surface lifecycle callback.
 * @param onSurfaceChanged Callback event triggered when the surface size changes.
 *                         - <b>surfaceHolder</b>: pointer to the {@link OH_ArkUI_SurfaceHolder} instance.
 *                         - <b>width</b>: new width of the surface after the size change.
 *                         - <b>height</b>: new height of the surface after the size change.
 * @since 19
 */
void OH_ArkUI_SurfaceCallback_SetSurfaceChangedEvent(
    OH_ArkUI_SurfaceCallback* callback,
    void (*onSurfaceChanged)(OH_ArkUI_SurfaceHolder* surfaceHolder, uint64_t width, uint64_t height));

/**
 * @brief Sets the destruction callback event in the surface lifecycle callback.
 *
 * @param callback Pointer to the surface lifecycle callback.
 * @param onSurfaceDestroyed Callback event triggered when the surface is destroyed.
 *                           - <b>surfaceHolder</b>: pointer to the {@link OH_ArkUI_SurfaceHolder} instance.
 * @since 19
 */
void OH_ArkUI_SurfaceCallback_SetSurfaceDestroyedEvent(
    OH_ArkUI_SurfaceCallback* callback,
    void (*onSurfaceDestroyed)(OH_ArkUI_SurfaceHolder* surfaceHolder));

/**
 * @brief Adds a surface lifecycle callback to an {@link OH_ArkUI_SurfaceHolder} instance.
 *
 * @param surfaceHolder Pointer to the {@link OH_ArkUI_SurfaceHolder} instance.
 * @param callback Pointer to the new callback.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 19
 */
int32_t OH_ArkUI_SurfaceHolder_AddSurfaceCallback(
    OH_ArkUI_SurfaceHolder* surfaceHolder,
    OH_ArkUI_SurfaceCallback* callback);

/**
 * @brief Removes a previously added surface lifecycle callback from an {@link OH_ArkUI_SurfaceHolder} instance.
 *
 * @param surfaceHolder Pointer to the {@link OH_ArkUI_SurfaceHolder} instance.
 * @param callback Pointer to the callback to be removed.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 19
 */
int32_t OH_ArkUI_SurfaceHolder_RemoveSurfaceCallback(
    OH_ArkUI_SurfaceHolder* surfaceHolder,
    OH_ArkUI_SurfaceCallback* callback);

/**
 * @brief Defines a struct for the <b>NativeWindow</b> instance.
 *
 * @since 19
 */
typedef struct NativeWindow OHNativeWindow;

/**
 * @brief Obtains the <b>NativeWindow</b> instance associated with an {@link OH_ArkUI_SurfaceHolder} instance.
 *
 * @param surfaceHolder Pointer to the {@link OH_ArkUI_SurfaceHolder} instance.
 * @return <b>NativeWindow</b> instance associated with the {@link OH_ArkUI_SurfaceHolder} instance.
 * @since 19
 */
OHNativeWindow* OH_ArkUI_XComponent_GetNativeWindow(OH_ArkUI_SurfaceHolder* surfaceHolder);

/**
 * @brief Sets whether the <b>XComponent</b> component needs to automatically initialize the surface.
 *
 * @param node Pointer to the <b>XComponent</b> component instance.
 * @param autoInitialize Whether the XComponent needs to automatically initialize the surface.
 *                       If <b>autoInitialize</b> is <b>true</b>, the <b>OnSurfaceCreated</b> callback will be
 *                       triggered when the component is attached to the tree, and the <b>OnSurfaceDestroyed</b>
 *                       callback will be triggered when the component is detached from the tree.
 *                       The default value of <b>autoInitialize</b> is <b>true</b>.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 19
 */
int32_t OH_ArkUI_XComponent_SetAutoInitialize(ArkUI_NodeHandle node, bool autoInitialize);

/**
 * @brief Initializes the surface held by the <b>XComponent</b> component.
 *
 * @param node Pointer to the <b>XComponent</b> component instance.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 *         {@link ARKUI_ERROR_CODE_XCOMPONENT_STATE_INVALID}: The surface held by the XComponent component has been
 *                                                            initialized.
 * @since 19
 */
int32_t OH_ArkUI_XComponent_Initialize(ArkUI_NodeHandle node);

/**
 * @brief Destroys the surface held by the <b>XComponent</b> component.
 *
 * @param node Pointer to the <b>XComponent</b> component instance.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 *         {@link ARKUI_ERROR_CODE_XCOMPONENT_STATE_INVALID}: The surface held by the XComponent component has been
 *                                                            destroyed.
 * @since 19
 */
int32_t OH_ArkUI_XComponent_Finalize(ArkUI_NodeHandle node);

/**
 * @brief Checks whether the surface held by the <b>XComponent</b> component is initialized.
 *
 * @param node Pointer to the <b>XComponent</b> component instance.
 * @param isInitialized Whether the surface held by the <b>XComponent</b> component is initialized.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 19
 */
int32_t OH_ArkUI_XComponent_IsInitialized(ArkUI_NodeHandle node, bool* isInitialized);

/**
 * @brief Sets the expected frame rate range for the <b>XComponent</b> component.
 *
 * @param node XComponent instance.
 * @param range Expected frame rate information object of the {@link OH_NativeXComponent_ExpectedRateRange} type.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 20
 * @version 1.0
 */
int32_t OH_ArkUI_XComponent_SetExpectedFrameRateRange(
    ArkUI_NodeHandle node, OH_NativeXComponent_ExpectedRateRange range);

/**
 * @brief Registers a frame callback function for the <b>XComponent</b> component.
 *
 * @param node XComponent instance.
 * @param callback Pointer to the frame callback function.
 *                 - <b>timestamp</b>: time when the current frame arrives, in nanoseconds.
 *                 - <b>targetTimestamp</b>: expected arrival time of the next frame, in nanoseconds.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 20
 * @version 1.0
 */
int32_t OH_ArkUI_XComponent_RegisterOnFrameCallback(ArkUI_NodeHandle node,
    void (*callback)(ArkUI_NodeHandle node, uint64_t timestamp, uint64_t targetTimestamp));

/**
 * @brief Unregisters the frame callback function for the XComponent.
 *
 * @param node XComponent instance.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 20
 * @version 1.0
 */
int32_t OH_ArkUI_XComponent_UnregisterOnFrameCallback(ArkUI_NodeHandle node);

/**
 * @brief Sets whether the soft keyboard is required for the <b>XComponent</b> component.
 * @param node XComponent instance.
 * @param needSoftKeyboard Whether the soft keyboard is required.
 * @return Result code.
 *         {@link ARKUI_ERROR_CODE_NO_ERROR}: The operation is successful.
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID}: A parameter error occurs.
 * @since 20
 */
int32_t OH_ArkUI_XComponent_SetNeedSoftKeyboard(ArkUI_NodeHandle node, bool needSoftKeyboard);

/**
 * @brief Creates an {@link ArkUI_AccessibilityProvider} instance for the <b>XComponent</b> component.
 *
 * @param node XComponent instance.
 * @return Pointer to the {@link ArkUI_AccessibilityProvider} instance.
 * @since 20
 */
ArkUI_AccessibilityProvider* OH_ArkUI_AccessibilityProvider_Create(ArkUI_NodeHandle node);

/**
 * @brief Destroys the {@link ArkUI_AccessibilityProvider} instance created using {@link ArkUI_AccessibilityProvider}.
 *
 * @param provider {@link ArkUI_AccessibilityProvider} instance created using
 *                 {@link OH_ArkUI_AccessibilityProvider_Create}.
 * @since 20
 */
void OH_ArkUI_AccessibilityProvider_Dispose(ArkUI_AccessibilityProvider* provider);

/**
 * @brief Sets a surface display callback for this {@link OH_ArkUI_SurfaceCallback} instance.
 *        The callback is invoked when the application window has returned to the foreground from the background.
 *
 * @param callback Pointer to the {@link OH_ArkUI_SurfaceCallback} instance.
 * @param onSurfaceShow Pointer to the surface display callback.
 *                      - <b>surfaceHolder</b>: pointer to the {@link OH_ArkUI_SurfaceHolder} instance.
 * @since 20
 */
void OH_ArkUI_SurfaceCallback_SetSurfaceShowEvent(
    OH_ArkUI_SurfaceCallback* callback,
    void (*onSurfaceShow)(OH_ArkUI_SurfaceHolder* surfaceHolder));

/**
 * @brief Sets a surface hiding callback for this {@link OH_ArkUI_SurfaceCallback} instance.
 *        The callback is invoked when the application window has entered the background from the foreground.
 *
 * @param callback Pointer to the {@link OH_ArkUI_SurfaceCallback} instance.
 * @param onSurfaceHide Pointer to the surface hiding callback.
 *                      - <b>surfaceHolder</b>: pointer to the {@link OH_ArkUI_SurfaceHolder} instance.
 * @since 20
 */
void OH_ArkUI_SurfaceCallback_SetSurfaceHideEvent(
    OH_ArkUI_SurfaceCallback* callback,
    void (*onSurfaceHide)(OH_ArkUI_SurfaceHolder* surfaceHolder));

#ifdef __cplusplus
};
#endif
#endif // _NATIVE_INTERFACE_XCOMPONENT_H_
